\section{Functions Shared by Encode and Decode}
\label{group__basefuncs}\index{Functions Shared by Encode and Decode@{Functions Shared by Encode and Decode}}
\subsection*{Basic shared functions}
\begin{CompactItemize}
\item 
const char $\ast$ {\bf th\_\-version\_\-string} (void)
\begin{CompactList}\small\item\em Retrieves a human-readable string to identify the library vendor and version. \item\end{CompactList}\item 
ogg\_\-uint32\_\-t {\bf th\_\-version\_\-number} (void)
\begin{CompactList}\small\item\em Retrieves the library version number. \item\end{CompactList}\item 
ogg\_\-int64\_\-t {\bf th\_\-granule\_\-frame} (void $\ast$\_\-encdec, ogg\_\-int64\_\-t \_\-granpos)
\begin{CompactList}\small\item\em Converts a granule position to an absolute frame index, starting at {\tt 0}. \item\end{CompactList}\item 
double {\bf th\_\-granule\_\-time} (void $\ast$\_\-encdec, ogg\_\-int64\_\-t \_\-granpos)
\begin{CompactList}\small\item\em Converts a granule position to an absolute time in seconds. \item\end{CompactList}\item 
int {\bf th\_\-packet\_\-isheader} (ogg\_\-packet $\ast$\_\-op)
\begin{CompactList}\small\item\em Determines whether a Theora packet is a header or not. \item\end{CompactList}\item 
int {\bf th\_\-packet\_\-iskeyframe} (ogg\_\-packet $\ast$\_\-op)
\begin{CompactList}\small\item\em Determines whether a theora packet is a key frame or not. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions for manipulating header data}
\begin{CompactItemize}
\item 
void {\bf th\_\-info\_\-init} ({\bf th\_\-info} $\ast$\_\-info)
\begin{CompactList}\small\item\em Initializes a \doxyref{th\_\-info}{p.}{structth__info} structure. \item\end{CompactList}\item 
void {\bf th\_\-info\_\-clear} ({\bf th\_\-info} $\ast$\_\-info)
\begin{CompactList}\small\item\em Clears a \doxyref{th\_\-info}{p.}{structth__info} structure. \item\end{CompactList}\item 
void {\bf th\_\-comment\_\-init} ({\bf th\_\-comment} $\ast$\_\-tc)
\begin{CompactList}\small\item\em Initialize a \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{CompactList}\item 
void {\bf th\_\-comment\_\-add} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-comment)
\begin{CompactList}\small\item\em Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{CompactList}\item 
void {\bf th\_\-comment\_\-add\_\-tag} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag, char $\ast$\_\-val)
\begin{CompactList}\small\item\em Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{CompactList}\item 
char $\ast$ {\bf th\_\-comment\_\-query} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag, int \_\-count)
\begin{CompactList}\small\item\em Look up a comment value by its tag. \item\end{CompactList}\item 
int {\bf th\_\-comment\_\-query\_\-count} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag)
\begin{CompactList}\small\item\em Look up the number of instances of a tag. \item\end{CompactList}\item 
void {\bf th\_\-comment\_\-clear} ({\bf th\_\-comment} $\ast$\_\-tc)
\begin{CompactList}\small\item\em Clears a \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{CompactList}\end{CompactItemize}


\subsection{Function Documentation}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-add@{th\_\-comment\_\-add}}
\index{th\_\-comment\_\-add@{th\_\-comment\_\-add}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-add ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, \/  char $\ast$ {\em \_\-comment})}\label{group__basefuncs_g19a1f7b8032db957df151a34e5ac9272}


Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. 

\begin{Desc}
\item[Note:]Neither \doxyref{th\_\-comment\_\-add()}{p.}{group__basefuncs_g19a1f7b8032db957df151a34e5ac9272} nor \doxyref{th\_\-comment\_\-add\_\-tag()}{p.}{group__basefuncs_g6c5edc201ca220a30787ca6c1ddcaeaf} support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the \doxyref{th\_\-comment}{p.}{structth__comment} structure directly. \end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to add the comment to. \item[{\em \_\-comment}]Must be a null-terminated UTF-8 string containing the comment in \char`\"{}TAG=the value\char`\"{} form. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-add\_\-tag@{th\_\-comment\_\-add\_\-tag}}
\index{th\_\-comment\_\-add\_\-tag@{th\_\-comment\_\-add\_\-tag}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-add\_\-tag ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, \/  char $\ast$ {\em \_\-tag}, \/  char $\ast$ {\em \_\-val})}\label{group__basefuncs_g6c5edc201ca220a30787ca6c1ddcaeaf}


Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. 

\begin{Desc}
\item[Note:]Neither \doxyref{th\_\-comment\_\-add()}{p.}{group__basefuncs_g19a1f7b8032db957df151a34e5ac9272} nor \doxyref{th\_\-comment\_\-add\_\-tag()}{p.}{group__basefuncs_g6c5edc201ca220a30787ca6c1ddcaeaf} support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the \doxyref{th\_\-comment}{p.}{structth__comment} structure directly. \end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to add the comment to. \item[{\em \_\-tag}]A null-terminated string containing the tag associated with the comment. \item[{\em \_\-val}]The corresponding value as a null-terminated string. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-clear@{th\_\-comment\_\-clear}}
\index{th\_\-comment\_\-clear@{th\_\-comment\_\-clear}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-clear ({\bf th\_\-comment} $\ast$ {\em \_\-tc})}\label{group__basefuncs_ge736c1afa514947a3feb223143af95e3}


Clears a \doxyref{th\_\-comment}{p.}{structth__comment} structure. 

This should be called on a \doxyref{th\_\-comment}{p.}{structth__comment} structure after it is no longer needed. It will free all memory used by the structure members. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to clear. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-init@{th\_\-comment\_\-init}}
\index{th\_\-comment\_\-init@{th\_\-comment\_\-init}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-init ({\bf th\_\-comment} $\ast$ {\em \_\-tc})}\label{group__basefuncs_g6c8ab25988e7ea9d7b1e31a54cf58f09}


Initialize a \doxyref{th\_\-comment}{p.}{structth__comment} structure. 

This should be called on a freshly allocated \doxyref{th\_\-comment}{p.}{structth__comment} structure before attempting to use it. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to initialize. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-query@{th\_\-comment\_\-query}}
\index{th\_\-comment\_\-query@{th\_\-comment\_\-query}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ th\_\-comment\_\-query ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, \/  char $\ast$ {\em \_\-tag}, \/  int {\em \_\-count})}\label{group__basefuncs_g33c8b4f57a03217636d704c2ebb211fa}


Look up a comment value by its tag. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]An initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item[{\em \_\-tag}]The tag to look up. \item[{\em \_\-count}]The instance of the tag. The same tag can appear multiple times, each with a distinct value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use \doxyref{th\_\-comment\_\-query\_\-count()}{p.}{group__basefuncs_g81d518dc4426f63ceaedcbe2668679fc} to get the legal range for the {\em \_\-count\/} parameter. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the queried tag's value. This points directly to data in the \doxyref{th\_\-comment}{p.}{structth__comment} structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em NULL}]If no matching tag is found. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-query\_\-count@{th\_\-comment\_\-query\_\-count}}
\index{th\_\-comment\_\-query\_\-count@{th\_\-comment\_\-query\_\-count}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int th\_\-comment\_\-query\_\-count ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, \/  char $\ast$ {\em \_\-tag})}\label{group__basefuncs_g81d518dc4426f63ceaedcbe2668679fc}


Look up the number of instances of a tag. 

Call this first when querying for a specific tag and then iterate over the number of instances with separate calls to \doxyref{th\_\-comment\_\-query()}{p.}{group__basefuncs_g33c8b4f57a03217636d704c2ebb211fa} to retrieve all the values for that tag in order. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]An initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item[{\em \_\-tag}]The tag to look up. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The number on instances of this particular tag. \end{Desc}
\index{basefuncs@{basefuncs}!th\_\-granule\_\-frame@{th\_\-granule\_\-frame}}
\index{th\_\-granule\_\-frame@{th\_\-granule\_\-frame}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-int64\_\-t th\_\-granule\_\-frame (void $\ast$ {\em \_\-encdec}, \/  ogg\_\-int64\_\-t {\em \_\-granpos})}\label{group__basefuncs_g95b10e76fc4c05d0240ea2dfd9fd62bd}


Converts a granule position to an absolute frame index, starting at {\tt 0}. 

The granule position is interpreted in the context of a given \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_f5cc40472b925456d42526a035d66edd} or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_843d70bb02563885a8d54b9c1a781729} handle (either will suffice). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-encdec}]A previously allocated \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_f5cc40472b925456d42526a035d66edd} or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_843d70bb02563885a8d54b9c1a781729} handle. \item[{\em \_\-granpos}]The granule position to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The absolute frame index corresponding to {\em \_\-granpos\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1}]The given granule position was invalid (i.e. negative). \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-granule\_\-time@{th\_\-granule\_\-time}}
\index{th\_\-granule\_\-time@{th\_\-granule\_\-time}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}double th\_\-granule\_\-time (void $\ast$ {\em \_\-encdec}, \/  ogg\_\-int64\_\-t {\em \_\-granpos})}\label{group__basefuncs_g707e1e281de788af0df39ef00f3fb432}


Converts a granule position to an absolute time in seconds. 

The granule position is interpreted in the context of a given \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_f5cc40472b925456d42526a035d66edd} or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_843d70bb02563885a8d54b9c1a781729} handle (either will suffice). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-encdec}]A previously allocated \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_f5cc40472b925456d42526a035d66edd} or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_843d70bb02563885a8d54b9c1a781729} handle. \item[{\em \_\-granpos}]The granule position to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The absolute time in seconds corresponding to {\em \_\-granpos\/}. This is the \char`\"{}end time\char`\"{} for the frame, or the latest time it should be displayed. It is not the presentation time. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1}]The given granule position was invalid (i.e. negative). \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-info\_\-clear@{th\_\-info\_\-clear}}
\index{th\_\-info\_\-clear@{th\_\-info\_\-clear}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-info\_\-clear ({\bf th\_\-info} $\ast$ {\em \_\-info})}\label{group__basefuncs_gb3d6441ab4a4969859ef5fd78a9e3c1c}


Clears a \doxyref{th\_\-info}{p.}{structth__info} structure. 

This should be called on a \doxyref{th\_\-info}{p.}{structth__info} structure after it is no longer needed. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-info}]The \doxyref{th\_\-info}{p.}{structth__info} struct to clear. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-info\_\-init@{th\_\-info\_\-init}}
\index{th\_\-info\_\-init@{th\_\-info\_\-init}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-info\_\-init ({\bf th\_\-info} $\ast$ {\em \_\-info})}\label{group__basefuncs_g430d9c605816a6ca0bdce3a0b965b926}


Initializes a \doxyref{th\_\-info}{p.}{structth__info} structure. 

This should be called on a freshly allocated \doxyref{th\_\-info}{p.}{structth__info} structure before attempting to use it. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-info}]The \doxyref{th\_\-info}{p.}{structth__info} struct to initialize. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-packet\_\-isheader@{th\_\-packet\_\-isheader}}
\index{th\_\-packet\_\-isheader@{th\_\-packet\_\-isheader}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int th\_\-packet\_\-isheader (ogg\_\-packet $\ast$ {\em \_\-op})}\label{group__basefuncs_g02f3f38261a9b39452d8a5e6f8737cc1}


Determines whether a Theora packet is a header or not. 

This function does no verification beyond checking the packet type bit, so it should not be used for bitstream identification; use \doxyref{th\_\-decode\_\-headerin()}{p.}{group__decfuncs_g006d01d36fbe64768c571e6a12b7fc50} for that. As per the Theora specification, an empty (0-byte) packet is treated as a data packet (a delta frame with no coded blocks). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-op}]An {\tt ogg\_\-packet} containing encoded Theora data. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 1}]The packet is a header packet \item[{\em 0}]The packet is a video data packet. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-packet\_\-iskeyframe@{th\_\-packet\_\-iskeyframe}}
\index{th\_\-packet\_\-iskeyframe@{th\_\-packet\_\-iskeyframe}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int th\_\-packet\_\-iskeyframe (ogg\_\-packet $\ast$ {\em \_\-op})}\label{group__basefuncs_gfe95cfd06f0fef413266c9168a66248a}


Determines whether a theora packet is a key frame or not. 

This function does no verification beyond checking the packet type and key frame bits, so it should not be used for bitstream identification; use \doxyref{th\_\-decode\_\-headerin()}{p.}{group__decfuncs_g006d01d36fbe64768c571e6a12b7fc50} for that. As per the Theora specification, an empty (0-byte) packet is treated as a delta frame (with no coded blocks). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-op}]An {\tt ogg\_\-packet} containing encoded Theora data. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 1}]The packet contains a key frame. \item[{\em 0}]The packet contains a delta frame. \item[{\em -1}]The packet is not a video data packet. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th\_\-version\_\-number@{th\_\-version\_\-number}}
\index{th\_\-version\_\-number@{th\_\-version\_\-number}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-uint32\_\-t th\_\-version\_\-number (void)}\label{group__basefuncs_gb723a75c0f95b3eb817f7f769846016b}


Retrieves the library version number. 

This is the highest bitstream version that the encoder library will produce, or that the decoder library can decode. This number is composed of a 16-bit major version, 8-bit minor version and 8 bit sub-version, composed as follows: 

\begin{Code}\begin{verbatim} (VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR)
\end{verbatim}
\end{Code}

 \begin{Desc}
\item[Returns:]the version number. \end{Desc}
\index{basefuncs@{basefuncs}!th\_\-version\_\-string@{th\_\-version\_\-string}}
\index{th\_\-version\_\-string@{th\_\-version\_\-string}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ th\_\-version\_\-string (void)}\label{group__basefuncs_g04846066738d9f2024fc9961162b2dbc}


Retrieves a human-readable string to identify the library vendor and version. 

\begin{Desc}
\item[Returns:]the version string. \end{Desc}
